﻿using System;
using System.Diagnostics;

namespace Bing
{
    /// <summary>
    /// Contains parameters for a request to the Phonebook <see cref="ApiHelper.SourceType"/>.
    /// </summary>
    [DebuggerDisplay("FileType={FileType}, SortBy={SortBy}")]
    public class PhonebookRequest: IBingRequest
    {
        /// <summary>
        /// Gets or sets the number of <see cref="PhonebookResult"/> objects to return for a request that specifies the Phonebook <see cref="ApiHelper.SourceType"/>.
        /// </summary>
        /// <value>Specifies the number of <see cref="PhonebookResult"/> objects to return for a request that specifies the Phonebook <see cref="ApiHelper.SourceType"/>.</value>
        /// <remarks>The default value for Phonebook.Count is 10, the minimum value is 1, and the maximum value is 25. Any value outside this range returns an error.</remarks>
        public UInt32 Count { get; set; }

        /// <summary>
        /// Gets or sets the offset requested, from zero, for the starting point of the result set to be returned for this <see cref="PhonebookRequest"/>.
        /// </summary>
        /// <value>Specifies the offset requested, from zero, for the starting point of the result set to be returned for this <see cref="PhonebookRequest"/>.</value>
        /// <remarks>
        /// The offset specifies the requested position in the result set for the response that is returned for this source.<br />
        /// Offset is typically used in conjunction with the Count property on the <see cref="PhonebookRequest"/> object, and the Total property on the <see cref="PhonebookResponse"/> object, to facilitate paging through long lists of results.<br />
        /// The default value for Offset is 0 (zero), and the maximum offset value is 1,000. If any other value is specified, the Bing API returns an error.<br />
        /// Search results are limited to the first 1,000 results. This means that the total of <see cref="Count"/> plus <see cref="PhonebookRequest.Offset" /> should not be greater than 1,000.<br />
        /// </remarks>
        public UInt32 Offset { get; set; }

        // TODO: Documentation Error: http://msdn.microsoft.com/en-us/library/dd250976.aspx, The introduction is required
        /// <summary>
        /// Gets or sets the type of phonebook to look through
        /// </summary>
        /// <value>The type of phonebook to look through.</value>
        /// <remarks>
        /// <table>
        ///     <tr><td><b>PhoneBook Listing Type</b></td><td><b>FileType Property Value</b></td></tr>
        ///     <tr><td>Commercial (Yellow Pages) Listings</td><td>YP</td></tr>
        ///     <tr><td>Residential (White Pages) Listings</td><td>WP</td></tr>
        /// </table>
        /// <b>NOTE</b><br />
        /// The PhoneBook listing types YP and WP are supported for U.S. markets (en-US and es-US) only.
        /// </remarks>
        public string FileType { get; set; }

        // TODO: Documentation Error: http://msdn.microsoft.com/en-us/library/dd250915.aspx, invalid type should be PhonebookSortOption
        /// <summary>
        /// Gets or sets the sort order of results returned from the PhoneBook <see cref="ApiHelper.SourceType"/>.
        /// </summary>
        /// <value>The sort order of results returned from the PhoneBook <see cref="ApiHelper.SourceType"/>.</value>
        public ApiHelper.PhonebookSortOption SortBy { get; set; }

        /// <summary>
        /// Gets or sets a phonebook Yellow page or white page ID.
        /// </summary>
        /// <value>A phonebook Yellow page or white page ID.</value>
        /// <remarks>
        /// The LocId is returned in the <see cref="PhonebookResult.UniqueId" /> property. You can use the ID to do a lookup on a specific phonebook entry.<br />
        /// For example: <b>YN925x15773933</b>.
        /// </remarks>
        public string LocID { get; set; }

        /// <summary>
        /// Creates the query string for the API call.
        /// </summary>
        /// <returns>The query string to append to the call.</returns>
        public string ToQueryString()
        {
            string request = string.Format("&Phonebook.Count={0}", Count);
            request += string.Format("&Phonebook.Offset={0}", Offset);
            request += string.Format("&Phonebook.FileType={0}", FileType);
            request += string.Format("&Phonebook.LocId={0}", LocID);
            request += string.Format("&Phonebook.SortBy={0}",
                                     Enum.GetName(typeof (ApiHelper.PhonebookSortOption), SortBy));

            return request;
        }
    }
}
